KCCreateKeychain

KCCreateKeychain
Header:	Keychain.h		Carbon status:	Under Evaluation

Creates an empty keychain.

OSStatus KCCreateKeychain (
    StringPtr password, 
    KCRef *keychain
);

Parameter descriptions

password: A pointer to a Pascal string representing the password string which will be used to protect the new keychain. If you pass NULL, the Keychain Setup dialog box will be displayed to obtain it.
keychain: A pointer to a reference to the keychain you wish to create. You create a reference by calling the function KCMakeKCRefFromFSSpec. If you pass a NULL pointer, KCCreateKeychain creates the new keychain in the Keychains folder. If you pass a valid reference pointing to NULL, the Keychain Manager allocates the memory for the keychain reference and returns it in this parameter. In this case, the keychain will be created in the Keychain folder.

function result: A result code. The result code userCanceledErr indicates that the user pressed the Cancel button in the create keychain. The result code errKCDuplicateKeychain indicates that the user tried to create a keychain which already exists. The result code errKCInvalidKeychain indicates that the specified keychain is invalid. Additional errors may be returned if the keychain could not be created (for example, a file system or network error may be returned if there is no write access to the storage media).

DISCUSSION

The KCCreateKeychain function creates an empty keychain. The keychain and password parameters are optional. If user interaction to create a keychain is posted, the newly-created keychain is automatically unlocked after creation.

You can also call the function kccreatekeychain to create an empty keychain. kccreatekeychain requires that you pass a pointer to a C string instead of a pointer to a Pascal string in the password parameter.

SPECIAL CONSIDERATIONS

When you are finished with a keychain, you must deallocate its memory by calling the function KCReleaseKeychain.

VERSION NOTES

Available beginning with Keychain Manager 1.0. In Keychain Manager 1.0, the kccreatekeychain function provides the same functionality as KCCreateKeychain. In Keychain 2.0, you should use KCCreateKeychain, since kccreatekeychain is provided for convenience only and may be removed from the header file at some point in the future.